home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / CIncludes / FindByContent.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  10.2 KB  |  349 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        FindByContent.h
  3.  
  4.      Contains:    Public search interface for the Find by Content shared library
  5.  
  6.      Version:    Technology:    2.0
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1997-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __FINDBYCONTENT__
  18. #define __FINDBYCONTENT__
  19.  
  20. #ifndef __MACTYPES__
  21. #include <MacTypes.h>
  22. #endif
  23. #ifndef __FILES__
  24. #include <Files.h>
  25. #endif
  26.  
  27.  
  28.  
  29. #if PRAGMA_ONCE
  30. #pragma once
  31. #endif
  32.  
  33. #ifdef __cplusplus
  34. extern "C" {
  35. #endif
  36.  
  37. #if PRAGMA_IMPORT
  38. #pragma import on
  39. #endif
  40.  
  41. #if PRAGMA_STRUCT_ALIGN
  42.     #pragma options align=mac68k
  43. #elif PRAGMA_STRUCT_PACKPUSH
  44.     #pragma pack(push, 2)
  45. #elif PRAGMA_STRUCT_PACK
  46.     #pragma pack(2)
  47. #endif
  48.  
  49.  
  50. enum {
  51.     gestaltFBCIndexingState        = FOUR_CHAR_CODE('fbci'),        /* Find By Content indexing state*/
  52.     gestaltFBCindexingSafe        = 0,                            /* any search will result in synchronous wait*/
  53.     gestaltFBCindexingCritical    = 1                                /* any search will execute immediately*/
  54. };
  55.  
  56.  
  57. enum {
  58.     gestaltFBCVersion            = FOUR_CHAR_CODE('fbcv'),        /* Find By Content version*/
  59.     gestaltFBCCurrentVersion    = 0x0011                        /* First release */
  60. };
  61.  
  62.  
  63. /*
  64.    ***************************************************************************
  65.    Phase values
  66.    These values are passed to the client's callback function to indicate what
  67.    the FBC code is doing.
  68.    ***************************************************************************
  69. */
  70.  
  71. enum {
  72.                                                                 /* indexing phases*/
  73.     kFBCphIndexing                = 0,
  74.     kFBCphFlushing                = 1,
  75.     kFBCphMerging                = 2,
  76.     kFBCphMakingIndexAccessor    = 3,
  77.     kFBCphCompacting            = 4,
  78.     kFBCphIndexWaiting            = 5,                            /* access phases*/
  79.     kFBCphSearching                = 6,
  80.     kFBCphMakingAccessAccessor    = 7,
  81.     kFBCphAccessWaiting            = 8,                            /* summarization*/
  82.     kFBCphSummarizing            = 9,                            /* indexing or access*/
  83.     kFBCphIdle                    = 10,
  84.     kFBCphCanceling                = 11
  85. };
  86.  
  87. /*
  88.    ***************************************************************************
  89.    FBC errors are assigned in the range -30500 to -30539, inclusive.
  90.    ***************************************************************************
  91. */
  92.  
  93.  
  94. enum {
  95.     kFBCvTwinExceptionErr        = -30500,                        /*no telling what it was*/
  96.     kFBCnoIndexesFound            = -30501,
  97.     kFBCallocFailed                = -30502,                        /*probably low memory*/
  98.     kFBCbadParam                = -30503,
  99.     kFBCfileNotIndexed            = -30504,
  100.     kFBCbadIndexFile            = -30505,                        /*bad FSSpec, or bad data in file*/
  101.     kFBCcompactionFailed        = -30506,                        /*V-Twin exception caught*/
  102.     kFBCvalidationFailed        = -30507,                        /*V-Twin exception caught*/
  103.     kFBCindexingFailed            = -30508,                        /*V-Twin exception caught*/
  104.     kFBCcommitFailed            = -30509,                        /*V-Twin exception caught*/
  105.     kFBCdeletionFailed            = -30510,                        /*V-Twin exception caught*/
  106.     kFBCmoveFailed                = -30511,                        /*V-Twin exception caught*/
  107.     kFBCtokenizationFailed        = -30512,                        /*couldn't read from document or query*/
  108.     kFBCmergingFailed            = -30513,                        /*couldn't merge index files*/
  109.     kFBCindexCreationFailed        = -30514,                        /*couldn't create index*/
  110.     kFBCaccessorStoreFailed        = -30515,
  111.     kFBCaddDocFailed            = -30516,
  112.     kFBCflushFailed                = -30517,
  113.     kFBCindexNotFound            = -30518,
  114.     kFBCnoSearchSession            = -30519,
  115.     kFBCindexingCanceled        = -30520,
  116.     kFBCaccessCanceled            = -30521,
  117.     kFBCindexFileDestroyed        = -30522,
  118.     kFBCindexNotAvailable        = -30523,
  119.     kFBCsearchFailed            = -30524,
  120.     kFBCsomeFilesNotIndexed        = -30525,
  121.     kFBCillegalSessionChange    = -30526,                        /*tried to add/remove vols to a session*/
  122.                                                                 /*that has hits*/
  123.     kFBCanalysisNotAvailable    = -30527,
  124.     kFBCbadIndexFileVersion        = -30528,
  125.     kFBCsummarizationCanceled    = -30529,
  126.     kFBCindexDiskIOFailed        = -30530,
  127.     kFBCbadSearchSession        = -30531,
  128.     kFBCnoSuchHit                = -30532
  129. };
  130.  
  131.  
  132. /*
  133.    ***************************************************************************
  134.    Pointer types
  135.    These point to memory allocated by the FBC shared library, and must be deallocated
  136.    by calls that are defined below.
  137.    ***************************************************************************
  138. */
  139.  
  140. /* A collection of state information for searching*/
  141. typedef struct OpaqueFBCSearchSession*     FBCSearchSession;
  142. /* An ordinary C string (used for hit/doc terms)*/
  143. typedef char *                            FBCWordItem;
  144. /* An array of WordItems*/
  145. typedef FBCWordItem *                    FBCWordList;
  146. /*
  147.    ***************************************************************************
  148.    Callback function type for progress reporting and cancelation during
  149.    searching and indexing.  The client's callback function should call
  150.    WaitNextEvent; a "sleep" value of 1 is suggested.  If the callback function
  151.    wants to cancel the current operation (indexing, search, or doc-terms
  152.    retrieval) it should return true.
  153.    ***************************************************************************
  154. */
  155.  
  156. typedef CALLBACK_API_C( Boolean , FBCCallbackProcPtr )(UInt16 phase, float percentDone, void *data);
  157. /*
  158.    ***************************************************************************
  159.    Set the callback function for progress reporting and cancelation during
  160.    searching and indexing, and set the amount of heap space to reserved for
  161.    the client's use when FBC allocates memory.
  162.    ***************************************************************************
  163. */
  164. EXTERN_API_C( void )
  165. FBCSetCallback                    (FBCCallbackProcPtr     fn,
  166.                                  void *                    data);
  167.  
  168. EXTERN_API_C( void )
  169. FBCSetHeapReservation            (UInt32                 bytes);
  170.  
  171. /*
  172.    ***************************************************************************
  173.    Find out whether a volume is indexed, the date & time of its last
  174.    completed  update, and its physical size.
  175.    ***************************************************************************
  176. */
  177.  
  178. EXTERN_API_C( Boolean )
  179. FBCVolumeIsIndexed                (SInt16                 theVRefNum);
  180.  
  181. EXTERN_API_C( Boolean )
  182. FBCVolumeIsRemote                (SInt16                 theVRefNum);
  183.  
  184. EXTERN_API_C( OSErr )
  185. FBCVolumeIndexTimeStamp            (SInt16                 theVRefNum,
  186.                                  UInt32 *                timeStamp);
  187.  
  188. EXTERN_API_C( OSErr )
  189. FBCVolumeIndexPhysicalSize        (SInt16                 theVRefNum,
  190.                                  UInt32 *                size);
  191.  
  192. /*
  193.    ***************************************************************************
  194.    Create & configure a search session
  195.    ***************************************************************************
  196. */
  197.  
  198. EXTERN_API_C( OSErr )
  199. FBCCreateSearchSession            (FBCSearchSession *        searchSession);
  200.  
  201. EXTERN_API_C( OSErr )
  202. FBCAddAllVolumesToSession        (FBCSearchSession         theSession,
  203.                                  Boolean                 includeRemote);
  204.  
  205. EXTERN_API_C( OSErr )
  206. FBCSetSessionVolumes            (FBCSearchSession         theSession,
  207.                                  const SInt16             vRefNums[],
  208.                                  UInt16                 numVolumes);
  209.  
  210. EXTERN_API_C( OSErr )
  211. FBCAddVolumeToSession            (FBCSearchSession         theSession,
  212.                                  SInt16                 vRefNum);
  213.  
  214. EXTERN_API_C( OSErr )
  215. FBCRemoveVolumeFromSession        (FBCSearchSession         theSession,
  216.                                  SInt16                 vRefNum);
  217.  
  218. EXTERN_API_C( OSErr )
  219. FBCGetSessionVolumeCount        (FBCSearchSession         theSession,
  220.                                  UInt16 *                count);
  221.  
  222. EXTERN_API_C( OSErr )
  223. FBCGetSessionVolumes            (FBCSearchSession         theSession,
  224.                                  SInt16                 vRefNums[],
  225.                                  UInt16 *                numVolumes);
  226.  
  227. EXTERN_API_C( OSErr )
  228. FBCCloneSearchSession            (FBCSearchSession         original,
  229.                                  FBCSearchSession *        clone);
  230.  
  231. /*
  232.    ***************************************************************************
  233.    Execute a search
  234.    ***************************************************************************
  235. */
  236.  
  237. EXTERN_API_C( OSErr )
  238. FBCDoQuerySearch                (FBCSearchSession         theSession,
  239.                                  char *                    queryText,
  240.                                  const FSSpec             targetDirs[],
  241.                                  UInt32                 numTargets,
  242.                                  UInt32                 maxHits,
  243.                                  UInt32                 maxHitWords);
  244.  
  245. EXTERN_API_C( OSErr )
  246. FBCDoExampleSearch                (FBCSearchSession         theSession,
  247.                                  const UInt32 *            exampleHitNums,
  248.                                  UInt32                 numExamples,
  249.                                  const FSSpec             targetDirs[],
  250.                                  UInt32                 numTargets,
  251.                                  UInt32                 maxHits,
  252.                                  UInt32                 maxHitWords);
  253.  
  254. EXTERN_API_C( OSErr )
  255. FBCBlindExampleSearch            (FSSpec                 examples[],
  256.                                  UInt32                 numExamples,
  257.                                  const FSSpec             targetDirs[],
  258.                                  UInt32                 numTargets,
  259.                                  UInt32                 maxHits,
  260.                                  UInt32                 maxHitWords,
  261.                                  Boolean                 allIndexes,
  262.                                  Boolean                 includeRemote,
  263.                                  FBCSearchSession *        theSession);
  264.  
  265.  
  266. /*
  267.    ***************************************************************************
  268.    Get information about hits [wrapper for THitItem C++ API]
  269.    ***************************************************************************
  270. */
  271.  
  272. EXTERN_API_C( OSErr )
  273. FBCGetHitCount                    (FBCSearchSession         theSession,
  274.                                  UInt32 *                count);
  275.  
  276. EXTERN_API_C( OSErr )
  277. FBCGetHitDocument                (FBCSearchSession         theSession,
  278.                                  UInt32                 hitNumber,
  279.                                  FSSpec *                theDocument);
  280.  
  281. EXTERN_API_C( OSErr )
  282. FBCGetHitScore                    (FBCSearchSession         theSession,
  283.                                  UInt32                 hitNumber,
  284.                                  float *                score);
  285.  
  286. EXTERN_API_C( OSErr )
  287. FBCGetMatchedWords                (FBCSearchSession         theSession,
  288.                                  UInt32                 hitNumber,
  289.                                  UInt32 *                wordCount,
  290.                                  FBCWordList *            list);
  291.  
  292. EXTERN_API_C( OSErr )
  293. FBCGetTopicWords                (FBCSearchSession         theSession,
  294.                                  UInt32                 hitNumber,
  295.                                  UInt32 *                wordCount,
  296.                                  FBCWordList *            list);
  297.  
  298.  
  299. /*
  300.    ***************************************************************************
  301.    Summarize a buffer of text
  302.    ***************************************************************************
  303. */
  304.  
  305. EXTERN_API_C( OSErr )
  306. FBCSummarize                    (void *                    inBuf,
  307.                                  UInt32                 inLength,
  308.                                  void *                    outBuf,
  309.                                  UInt32 *                outLength,
  310.                                  UInt32 *                numSentences);
  311.  
  312. /*
  313.    ***************************************************************************
  314.    Deallocate hit lists, word arrays, and search sessions
  315.    ***************************************************************************
  316. */
  317.  
  318. EXTERN_API_C( OSErr )
  319. FBCReleaseSessionHits            (FBCSearchSession         theSession);
  320.  
  321. EXTERN_API_C( OSErr )
  322. FBCDestroyWordList                (FBCWordList             theList,
  323.                                  UInt32                 wordCount);
  324.  
  325. EXTERN_API_C( OSErr )
  326. FBCDestroySearchSession            (FBCSearchSession         theSession);
  327.  
  328.  
  329. #if PRAGMA_STRUCT_ALIGN
  330.     #pragma options align=reset
  331. #elif PRAGMA_STRUCT_PACKPUSH
  332.     #pragma pack(pop)
  333. #elif PRAGMA_STRUCT_PACK
  334.     #pragma pack()
  335. #endif
  336.  
  337. #ifdef PRAGMA_IMPORT_OFF
  338. #pragma import off
  339. #elif PRAGMA_IMPORT
  340. #pragma import reset
  341. #endif
  342.  
  343. #ifdef __cplusplus
  344. }
  345. #endif
  346.  
  347. #endif /* __FINDBYCONTENT__ */
  348.  
  349.